.\" This manual was prepared by United States Government employees as a
.\" part of their official duties and is, therefore, a work of the U.S.
.\" Government and not subject to copyright.
.\"
.\" $Id: dataprobe.1,v 2.1.0.2 1997/10/27 18:37:10 dar Exp $
.TH DATAPROBE 1 "12 June 1995"

.SH NAME
Data Probe - STEP editing tool
.SH SYNOPSIS
.B dp_{schema_name} 
[
.B -saveFile 
.I file-name
] 
[
.B -saveFreq
.I integer
]
[
.B -workFile 
.I file-name
] 
[
.B -exchangeFile 
.I file-name
] 
[
.B -restrict
] 

.SH DESCRIPTION
.LP
The Validation Testing System (VTS) Data Probe software is a program
for browsing and editing data corresponding to a conceptual model
described using the language Express.  A separate program (fedex_plus)
reads in a schema and generates source code to represent the schema in
C++.  This code is linked with the libraries in the STEP Class Library
to create a schema specific editor.  The editor is X Windows based and
uses the InterViews Toolkit from Stanford.

.SH OPTIONS

.TP
.B \-s \fIfilename\fP, \fB-saveFile \fIfilename\fP
Designates an alternate backup file.  The default file is dpAutoSave.wf.
.TP
.B \-sf \fIseconds\fP, \fB-saveFreq  \fIseconds\fP
Specifies the frequency with which a backup file will be saved.  The default frequency is 30 seconds.
.TP
.B \-wf \fIfilename\fP, \fB-workFile  \fIfilename\fP
Specifies a working file to be loaded into the Data Probe.
.TP
.B \-ef \fIfilename\fP, \fB-exchangeFile \fIfilename\fP
Specifies a STEP exchange file to be loaded into the Data Probe.
.TP
.B \-r, \fB-restrict \fP
Restricts the file chooser menu to files not beginning with a '.'.

.SH USAGE
.LP
The Data Probe supports the editing of data in the format specified in
Part 21 of the ISO 10103.  It allows the user to create or modify
instance data, to check for consistency with an Express schema and to
examine the relationships of entities within the schema.  These
functions are supported in one or more of the following five types of
Data Probe windows:

.nf
    Data Probe Window: supports general Data Probe func-
    tionalities, including file management, schema list
    browsing, and quitting Data Probe.

    Entity Type List window: contains a scrollable list
    of schema-specific entities for browsing or creating
    instances of entities.

    Entity Instance List window: contains a scrollable
    list of instances of entities.  Supports data view-
    ing and modification. 

    STEP Entity Editor window:  occurs for each instance
    being edited. Supports several data editing opera-
    tions including modify, delete and save.

    STEP Entity Descriptor window: contains information
    pertaining to an entity type including the list of
    attributes and subtypes for the selected entity.

    Each of these windows is described in detail below.
.fi
.LP
.I
DATA PROBE WINDOW
.nf

The Data Probe window is one of three windows appearing
initially when the Data Probe is run.  It is composed of
the following four sections:

             1. title
             2. menu bar
             3. quick reference
             4. message bar

Each of these sections is described in detail below:

.I
Data Probe Window title section:
.fi
.LP
The title section shows the name of the schema for which the Data
Probe was created preceeded by the prefix 'DP-'.
.nf
   
.I
Data Probe Window menu bar section:

The menu bar consists of two pull-down menus labeled
Quit and File Management.

   The Quit pull-down menu allows the user to exit Data
   Probe. No warnings will be given before exiting. 
  
   The File Management pull-down menu allows the user to
   perform operations on the following file types:

     Exchange Files  Data saved to these files must be in 
                     complete STEP file format and must be 
                     provided for all required attributes 
                     in order to be used by application 
                     programs that will rely on this data.                   

     Working Files   These  files will not be used by appli-
                     cation programs and serve the purpose 
                     of storing intermediate data for saving
                     the editing session.

     Backup File     This file is written regularly during
                     a Data Probe session to contain the
                     current Entity Instance List data.  The
                     backup file is written in Working File
                     form.  The default backup file is 
                     dpAutoSave.wf and is written to the 
                     directory where the command to run Data 
                     Probe was issued unless instructed
                     otherwise by the user (See 'Backup File'
                     in table below and OPTIONS above).
                     

   The File Management pull-down menu supports file manage-
   ment and other options as follows:   

   Options 
   Available
.I
   with              Options  Description

   Exchange File/    read     replaces previous contents of
   Working File               Entity Instance List data 
                              with the data in the file
                              selected.
                                  
                     write    writes Entity Instance List
                              data to the file selected and
                              erases the previous contents
                              of the file, if any.
                                  
                     append   writes Entity Instance List
                     from     data to the file selected.

   
                 
   Backup File       choose   selects an alternate backup
                              file to which Entity Instance
                              List data will be periodic-
                              ally written.  

                     write    writes Entity Instance List
                              data to current backup file 
                              selected.

   

   Entity            verify   verifies that the instances
   Instance List              found in the Entity Instance
                              List are complete according
                              to the schema specification.

                     remove   removes all instances in the
                              Entity Instance List which
                              are marked for deletion.

                     clear    clears all instances found
                              in the Entity Instance List
                              regardless of their current
                              edit state (see the ENTITY 
                              INSTANCE LIST section).

.I
Data Probe Window quick reference section:

   This section shows the key bindings and button codes 
   available in the Step Entity Editor windows to perform the
   following operations:

        - close existing window

        - open a new window

        - get value from list

.I
Data Probe Window message bar section:

   This section shows any resulting messages from actions 
   taken in any of the windows.  The Clear button on left
   enables the user to clear the current message shown.

.fi
.LP
.I
ENTITY TYPE LIST WINDOW

The Entity Type List is the second of the three windows appearing initially when the Data Probe is run.  The Entity Type List displays the list of schema-specific entity types. In addition to the operations outlined in 'Using Lists' below, the Entity Type List allows the user to create an instance as follows:
.nf

.I
Creating an Instance

    1. Select an entity type from the type list.

    2. Select Create

        -  use Create button or

        -  type 'C'.

    3. A STEP Entity Editor window appears for editing 
       the entity selected (See the STEP Entity Editor
       Window section below).



.fi
.I
ENTITY INSTANCE LIST WINDOW

The Entity Instance List is the third of three windows initially appearing when the Data Probe is run.  When an entity is selected from the Entity Type List or when instances are read in from a file, the instanced entities will appear on the Entity Instance List.  In addition to the operations outlined in 'Using Lists' below, the Entity Instance List allows the user to view, modify, and save instances of entities.
.nf

.I
Edit State Markers:
.fi
.LP
The selection of any of the preceeding options is represented by an edit state code.  An instance can be marked with an edit state option by typing the key which correlates to that option.  The marked option is shown in lower case on the left of the selected instance.  When the execute button is pressed, all marked options will be executed, reflected by an upper case letter edit state code which replaces the lower case marker to the left of the intance.

Below is a description of Entity List edit state codes and the keys that are used to select them:

KEY                 OPERATION                    EDIT STATE

 s   save complete (no capital letter) -- All     (blank)
     attribute values associated with the 
     instance must be  valid and all required 
     attributes must exist.

 i   save incomplete -- All attribute values         I
     associated with the instance must be  
     valid, however all required attributes 
     may not exist.  This allows attribute 
     values to be saved even though the entity 
     is incomplete.  It also provides a way 
     for a user to mark an instance as needing 
     further attention even if all required 
     attributes exist.

 d   delete -- the entities in this edit             D
     state will be deleted when the contents 
     of the instance list are written to a 
     file.

 m   modify -- open an editor window for             M
     modifying instances.

 v   view -- open an editor window for view-         V
     ing only.



.I
STEP ENTITY EDITOR (SEE) WINDOW 

The edit state options described above can also be executed from the STEP Entity Editor Window (SEE).  The SEE Window is opened whenever the modify or view option is executed from the Entity Instance List or when an entity is created from the Entity Type List.  The following are the operations supported in the SEE window:

.nf
.I
Changing the Edit State of an Entity

 save instance to a complete state       C-x C-s

 save instance to an incomplete state    C-x C-i

 cancel changes to the entity; reverts   C-x C-c
 all attribute values to the last 
 saved (complete or incomplete) values

 mark instance for deletion              C-x C-d

 Each of the above options can also be selected by 
 clicking the corresponding button in the SEE win-
 dow.

.I
Selecting an Attribute

 Using mouse:
 
  Point the mouse cursor inside the attribute
  editing box desired and click the left mouse
  button.

 Using key bindings:

  select next attribute                  C-n

  select previous attribute              C-p

.I
Editing an Attribute

 Using mouse:

  Point the mouse cursor inside the desired editing
  box and click the left mouse button to place the
  cursor at the desired postion inside the editing
  box.

 Using key bindings:

  move cursor forward                    C-f 

  move cursor backward                   C-b

  move cursor to the end                 C-e

  move cursor to the beginning           C-a

  move cursor one word forward           <esc>-f

  move cursor one word backward          <esc>-b

 Delete and undo: 

  deleting a portion of the attribute

    1. Point the mouse cursor inside the desired attri-
       bute editing box, click and hold the left mouse
       button.
    2. Drag the mouse to the left or right to highlight 
       desired text.
    3. Press <delete> or input a value to replace selec-
       ted text.

  delete a character in place            C-d

  delete the previous character          <delete> or 
                                         C-h

  select the remainder of the word 
  following the cursor to be deleted     C-w

  select everything following the        C-k
  cursor to be deleted

  select the entire text to be deleted   C-u

  undo attribute (revert attribute to    C-x C-u
  the last saved value)

 Scrolling:
 
  horizontal grab scroll - use left mouse button

   1. Point the mouse inside the attribute list.

   2. Press and hold the middle mouse button.

   3. Slide the mouse left or right to scroll 
      the window in the same direction.

  horizontal rate scroll - use right mouse button

   1. Point the mouse inside the  attribute list.

   2. Press and hold the right mouse button.

   3. Slide the mouse left or right to scroll 
      the window in the same direction.

 The following editing actions are permissable on attributes 
 that are of type entity only:

  edit entity - press the edit button (marked e) or type
                C-x C-e 

   If the attribute contains an entity id, the 
   identified entity will be put on the screen 
   in a STEP Entity Editor window.  

   If the attribute is empty, a new entity of 
   the type corresponding to the attribute type
   will be created and  displayed on the screen
   in a STEP Entity Editor window.   The entity
   id corresponding to the newly created entity 
   will be filled in for the attribute.

  select marked entity - press the select mark button 
                         (marked m) or type C-x C-m:

   The entity id of the selected entity from the
   Entity  Instance List will be filed in for the
   current atttribute. 


.fi
.LP
.I
STEP ENTITY DESCRIPTOR WINDOW (SED)

The SED window enables the user to review information regarding an entity type.  It may be opened by selecting the Type Information box in the Entity Type List or SEE window (See the Entity Type List and STEP Entity Editor window sections above).  A SED window may also be opened from within a SED window as is described below. 
.nf

   Format of a SED window:

   1. Entity Descriptor Boxes

      The body of a SED window is composed of entity descrip-
      tor boxes.  These boxes are shown in order of inheri-
      tance starting with the selected entity type at the bot-
      tom of the window up to the root entity type shown at the
      top of the window. Each entity descriptor box contains a
      title bar, an attribute list and a subtype list described
      below.

        title bar - contains the name of the entity 
        in bold print at the left corner and the schema 
        in which the entity is defined at the right corner.

        attribute list - a scrollable list of attributes 
        defined in the corresponding entity shown on the 
        left side of the descriptor box.

        subtype list - a scrollable list of the subtypes 
        of the corresponding entity shown on the right side 
        of the descriptor box.

    2. Attr. Type subwindow 

       The Attr. Type subwindow shown at the bottom of the SED
       window displays further information regarding a selected
       attrtibute.    

   Using a SED window:

   1. Scrolling the attribute/subtype list

      a. Place mouse pointer on up/down arrow.

      b. Press right mouse button.

   2. Viewing a detailed description of an attribute:

      a. Place mouse pointer on desired
         attribute.

      b. Double click mouse button.  A detailed description
         of the attribute type will be displayed in the 
         Attr. Type subwindow located at the bottom of the
         SED window.

   3. Opening a SED window from the current SED window:

      a. Place mouse cursor on the desired entity from
         an entity subytpe list.

      b. Double click the mouse button.  A new SED window
         will appear for the entity type selected.

   3. Collapsing/Uncollapsing a descriptor box

      Collapse - show title bar only 
      Uncollapse - show attribute and subtype lists

      a. Place mouse cursor on collapse button of desired
         descriptor box.

      b. Click left mouse button.  This will cause the 
         descriptor box to switch from uncollapsed to 
         collapsed or vice-versa depending on the current
         state of the descriptor box.

   Exiting a SED window:

   1. Place mouse pointer on close button on left
      top corner of window

   2. Press left mouse button

   Warning: Do not use the standard close and quit
            options provided for windows.  This may
            cause you to inadvertantly quit the Data
            Probe session.  Use the close button pro-
            vided.

.fi
.LP
.I
USING LISTS

The following instructions are applicable to both the Entity Instance List and the Entity Type List.

.nf
.I
Selecting an Entry

   Using mouse:

    Positon the mouse on the entry and click the left
    mouse button.

   Using keystroke commands:

    search formward, selects the entry containing   C-s
    the substring specified in the search window   

    reverse search, selects the entry containing    C-r
    the substring specified in the search window

    select next entry                               C-n  

    select previous entry                           C-p

    select top entry                                <

    select bottom entry                             >

    deselect selected entry                         C-h 
                                                    <delete>

.I
Reviewing Information Regarding an Entity Type

 Allows the user to view information regarding attributes
 and subtypes and supertypes of an entity type using a 
 STEP ENTITY DESCRIPTOR (SED) window:

   Opening a SED window:

   1. Select an entity type from list.

   2. Select Type Information by placing the
      mouse pointer on the Type Information
      box and pressing the left mouse button. 

 For information on the use of the SED window, see the
 STEP Entity Editor window section above.

.I
Scrolling Lists 

 Using mouse:

   1. Position the mouse pointer to the scroll bar and
      click.

   2. Click (and optionally hold) the up mover or down
      mover located above and below the scroll bar 
      respectively to scroll bar.

   vertical grab scroll -- use middle mouse button

    1. Point the mouse cursor inside the list.

    2. Press and hold the right mouse button.

    3. Slide the mouse up or down to move the display
       up or down as desired.

   vertical rate scroll -- use right mouse button

    1. Point the mouse cusor inside the list.

    2. Press and hold the right mouse button.

    3. Slide the mouse up or down to scroll the list in
       the desired direction at a rate increasing as the
       mouse is moved away from its original position.

 Using key bindings:

    scroll list to beginning         C-a

    scroll list to end               C-e  

    scroll up                        C-b 
                                     C-k 

    scroll down                      C-f  
                                     C-j
    
    page down                        C-v
                                     ' '    

    half page down                   C-d 

    half page up                     C-u

.fi
.I
USING BUTTONS TO SELECT OPTIONS

Many of the Data Probe options can be selected by using keystroke commands as described.  Some options, however may be selected by using the selection buttons which correspond to those options as follows:
.nf
  
   1. Activate pull-down menu (if applicable):

     - Place mouse pointer on menu button

     - Press right mouse button and hold

   2. Select an option

     - Place mouse pointer on selection button correspond-
       ing to the desired option

     - Press left mouse button to activate option

.fi
.SH SEE ALSO
mkProbe(1)
.LP
ISO 10303-11:1994 
.I 
\Industrial automation systems and integration - Product data \
representation and exchange - Part 11: Description Methods: The \
EXPRESS Language Reference Manual.
.LP
ISO 10303-21:1994 
.I 
\Industrial automation systems and integration - Product data \
representation and exchange - Part 21: Implementation methods: \
Clear text encoding of the exchange structure.
.LP
Morris, K.C., Sauderd, D., Ressler, S., 
.I 
\Validation Testing System: Reusable Software Component Design, 
NISTIR 4937, National Institute of Standards and Technology, October
1992.
.LP
Sauder, D.,
.I 
\Data Probe Users Guide,
NISTIR 5141, National Institute of Standards and Technology, March
1993.

.SH NOTE
.LP
The source code for the Data Probe was designed with reusability in
mind.  The code uses the STEP Class Library (developed at NIST) and
the InterViews Toolkit (from Stanford).  The STEP Class Library is
divided into four libraries: Stepcore & Editor, Utilities, General
User Interface, and Probe.  Dependencies between these modules has
been minimized so that the executable program, the Data Probe, can be
easily reconfigured to support different conceptual schemas.

All NISTIR documents may be obtained through the National Technical
Information Service (NTIS), Springfield VA 22161, USA.  Postscript
files may be obtained through anonymous ftp from ftp.cme.nist.gov (see
pub/step/nptdocs/readme.txt to determine the appropriate file to
download).
